Skip to content

docs(protocol): 删除 runtime-capabilities 页 —— 整页教已于 #3605 删除的 ObjectStackCapabilities (#4781) - #4816

Merged
xuyushun441-sys merged 1 commit into
mainfrom
claude/issue-4781-retire-runtime-capabilities-page
Aug 3, 2026
Merged

docs(protocol): 删除 runtime-capabilities 页 —— 整页教已于 #3605 删除的 ObjectStackCapabilities (#4781)#4816
xuyushun441-sys merged 1 commit into
mainfrom
claude/issue-4781-retire-runtime-capabilities-page

Conversation

@xuyushun441-sys

Copy link
Copy Markdown
Contributor

Fixes #4781

按 issue 作者与 PM 裁定的方案 1(删页)执行:删除 content/docs/protocol/kernel/runtime-capabilities.mdx,只把其中经核实确实准确的 discovery 内容并入 API 文档。

为什么删

该页从头到尾教 ObjectStackCapabilities(data / ui / system 三子系统描述符),含两个完整的 const capabilities: ObjectStackCapabilities = {...} 示例和一个 hasCapability() 辅助函数。这个 schema 已在 #3605 删除:

  • import type { ObjectStackCapabilities } from '@objectstack/spec' 是 TS2305,照抄的读者第一行就编译失败;
  • 页内表格的键(queryDistinct / queryHaving / queryJoins / geoSpatial ……)不属于任何现存 schema;
  • 页面自己把「AI Agents: Understanding platform constraints for code generation」列为受众 —— 我们在把一个不存在的能力协商面教给代码生成器。

运行时能力发现的活机制是 REST discovery 端点 + 驱动侧 DriverCapabilities(#4634 之后)。

页尾那节 discovery,核实结果是「也不准」

Issue 说页尾 discovery 那节「反而是准的」。照实现核对后,不成立 —— 所以没有原样搬走,否则只是把缺陷换个地方放:

页面写的 实现是什么
GET /api/v1/discovery 返回体含 name / environment / locale ObjectStackProtocolImplementation.getDiscovery()(packages/metadata-protocol/src/protocol.ts)返回 { version, apiName, routes, services, capabilities } —— 三个字段一个都没有。它们属于 dispatcher 服务的 /.well-known/objectstack(packages/runtime/src/http-dispatcher.tsgetDiscoveryInfo),而 content/docs/api/index.mdx 早已把这两者的差别写对了
routes 里有 "graphql": "/graphql" ApiRoutesSchema(packages/spec/src/api/discovery.zod.ts)没有 graphql 键,serviceToRouteKey 也从不映射它 —— 纯属虚构
"version": "1.0.0" REST 处理器用 config.api.version 覆盖(v1)
「response follows the DiscoverySchema REST 实际返回体缺 DiscoverySchema 的必填 name / environment / locale,并不满足该 schema

并入 API 文档的部分(逐条对实现核实过)

content/docs/api/index.mdx## Discovery 一节补两点,都是删页里唯一站得住、且 API 文档此前没有明说的事实:

  1. GET /api/v1GET /api/v1/discovery 是同一个 handler 注册在两个路径上(registerDiscoveryEndpoints,packages/rest/src/rest-server.ts)—— 不是重定向,也不是两种形状。REST 插件挂载时 dispatcher 会把 <basePath>/discovery 让给它(单一 owner,ADR-0076 D11),只有 REST-less 组合里 dispatcher 才是该路由的 fallback owner。
  2. capabilities 映射与 transactionalBatch(discovery 广播「跨对象原子 batch」能力位(让客户端声明式协商,取代 404/405/501 运行时探测) #3298 / ADR-0034):当且仅当 POST {basePath}/batch 已挂载引擎能承担事务时为 true(protocol 由 engine.transaction 推导,rest-server 再与 api.enableBatch 相与)—— declared === enforced,客户端可在 connect 时一次谈妥,不必用 404/405/501 探测。

删页后遗症清理

  • content/docs/protocol/kernel/meta.json 移除导航项;
  • 两处入链改指:content/docs/automation/index.mdx → HTTP API,content/docs/kernel/index.mdx → 移除该项;
  • scripts/role-word-baseline.json 按棘轮下调(check-role-word 在被基线登记的文件消失时会报错,要求 ratchet DOWN)。

全仓搜过 runtime-capabilitiesRuntime Capabilities/docs/protocol/kernel/runtime-capabilitiesObjectStackCapabilitieshasCapability,覆盖 content/docs/**skills/**apps/**docs/**.github/**README.md:零活链接残留。唯一命中是 docs/audits/2026-06-handwritten-docs-accuracy-followups.md 里的历史审计记录(用的还是重命名前的 protocol/objectos/ 路径),属存档记录,不动。

skills/objectstack-platform/SKILL.md 提到 ObjectStackCapabilities 一次,是准确的历史说明(说明 FeatureFlagSchema 及其协议归宿都已死、活的是 GET /api/v1/discovery),不是在教用法,保留。

门禁

$ pnpm --filter @objectstack/spec check:docs
✅ import examples resolve against api-surface.json (137 accepted gap(s) in the baseline)
✅ 246 generated files in sync with packages/spec

$ node scripts/check-role-word.mjs
check-role-word: OK (43 baselined file(s), no new occurrences).

$ node scripts/check-doc-authoring.mjs
✓ doc authoring guard: 215 files clean — no bare metadata literals.

纯文档改动,不发布任何包 —— 按仓库惯例给了空 frontmatter changeset(Check Changeset 要求每个 PR 都新增一个 changeset,空 frontmatter 是「本 PR 不发布」的官方写法)。

🤖 Generated with Claude Code

https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ


Generated by Claude Code

…ved ObjectStackCapabilities schema (#4781)

`content/docs/protocol/kernel/runtime-capabilities.mdx` documented
`ObjectStackCapabilities` (data/ui/system subsystem descriptors) end to end,
including two full `const capabilities: ObjectStackCapabilities = {...}`
examples and a `hasCapability()` helper. That schema was removed in #3605:
`import type { ObjectStackCapabilities } from '@objectstack/spec'` is TS2305,
and none of the tabled keys (`queryDistinct`, `queryHaving`, `queryJoins`,
`geoSpatial`, …) exist in any live schema. The page named "AI Agents:
Understanding platform constraints for code generation" as an audience, so it
was teaching a non-existent capability-negotiation surface to code generators.

Delete the page. The live mechanisms are the REST discovery endpoint and the
driver-side `DriverCapabilities` (post-#4634).

The page's trailing "Discovery Endpoint" section was NOT accurate either and is
deliberately not moved verbatim. Checked against the implementation:

  - `ObjectStackProtocolImplementation.getDiscovery()`
    (packages/metadata-protocol/src/protocol.ts) returns
    `{ version, apiName, routes, services, capabilities }` — no `name`, no
    `environment`, no `locale`. The page showed all three on
    `GET /api/v1/discovery`; those fields belong to the *dispatcher*-served
    `/.well-known/objectstack` payload (packages/runtime/src/http-dispatcher.ts
    `getDiscoveryInfo`), which `content/docs/api/index.mdx` already documents
    correctly and separately.
  - The page's sample carried `routes.graphql: "/graphql"`. `ApiRoutesSchema`
    (packages/spec/src/api/discovery.zod.ts) has no `graphql` key and
    `serviceToRouteKey` never maps one — flatly wrong.
  - `version: "1.0.0"` — the REST handler overrides it with
    `config.api.version` (`v1`).

Folded into content/docs/api/index.mdx only the parts that verify:

  - `GET /api/v1` and `GET /api/v1/discovery` are one handler registered at two
    paths (`registerDiscoveryEndpoints`, packages/rest/src/rest-server.ts), and
    the dispatcher cedes `<basePath>/discovery` to REST when mounted
    (ADR-0076 D11) — it owns the route only in REST-less compositions.
  - The `capabilities` map and `transactionalBatch` (#3298 / ADR-0034): true
    iff `POST {basePath}/batch` is mounted AND the engine can honour a
    transaction (protocol derives it from `engine.transaction`, rest-server
    ANDs it with `api.enableBatch`).

Also: meta.json nav entry removed; the two inbound links (automation/index.mdx,
kernel/index.mdx) repointed; scripts/role-word-baseline.json ratcheted down for
the removed file (check-role-word fails on a vanished baselined file).

Docs-only, releases nothing — empty changeset.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ
@vercel

vercel Bot commented Aug 3, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
objectstack Ignored Ignored Aug 3, 2026 8:27am

Request Review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/l tooling

Projects

None yet

2 participants